<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">

<html>
<head>
   <META NAME="keywords" CONTENT="CSW, Ramsoft, ZX Spectrum, TZX, tapes">
	<title>WWR - CSW technical specifications</title>
	<basefont face="Verdana">
</head>

<body TEXT="#000000" BGCOLOR="#FFFFFF" LINK="#0000FF" VLINK="#800080" ALINK="#FF0000">

<center>
<table bgcolor="#0040ff" width="50%" border=0>
<tr><td align="center"><font size="+4" color="#ffff40"><strong>CSW FORMAT</strong></font></td></tr>
</table>
<br>
<font size="+1"><strong>Compressed Square Wave</strong></font><br>
<em><font size="-1">Created by Ramsoft ZX Spectrum demogroup</font></em>
<br><br>
<font><strong>Format revision: v2.00 (August 1st 2003)</strong></font>
<br><br>
</center>
<br><br>

<div align=center>
<TABLE WIDTH="40%">
<TR><TD ALIGN=LEFT><OL>
<LI><B><A HREF="#INTRODUCTION">Introduction</A></b></LI>
<LI><B><A HREF="#CSWUTIL">The CSW utility</A></B></LI>
<LI><B><A HREF="#CSW2FORMAT">CSW file format</A></B></LI>
<LI><B><A HREF="#CSW1FORMAT">Old CSW 1.01 file format</A></B></LI>
<LI><B><A HREF="#CONTACT">Contact information</A></B></LI>
<LI><B><A HREF="#HISTORY">Revision history</A></B></LI>
</OL></TD></TR></TABLE>
</div><br><br>


<a name="INTRODUCTION"></a>
<p><table bbgcolor="#ffff90" width="100%" cellspacing="12" cellpadding="0" border="0"><tr>
<td align="center" bgcolor="#ff7848" width="10%"><font size="+2" color="white"><b>
1.
</b></font></td><td><font size="+2">
Introduction
</font></td></tr></table>
<br>
<table width="100%" border="0"><tr><td width="10%"> </td></td><td>
This document describes the CSW file format and the CSW.EXE utility. CSW is strongly based upon the MakeTZX engine and it shares with it various aspects of its behaviour. In the manual of MakeTZX you will find lots of explanations, tips and FAQ that are not reported here, so we recommend you to read it too.

<br><br>
<b>The CSW file format</b>
<br><br>

CSW files are a way of storing sample data in a compact form, typically taking 1/10th of an ordinary VOC. It is used internally by MakeTZX, but it is also very useful to keep down the disk space taken by your VOC/WAV files. The CSW utility can handle CSW conversion in both ways (see below). Of course, MakeTZX itself accepts CSW files for input. 
When converting to the CSW format, the sample file is processed through MakeTZX's internal digital filter which reduces noise and signal distortions very efficiently. Make a backup copy of the original file if you will need the original samples later, but remeber that in most cases the CSW will be a lot better than the original file. 
Note that CSWs are intended for use with square waves only (such as computer tapes)! 
The compression ratio depends on many factors; in general, the higher the sample rate, the higher the ratio. A clean and regular signal helps too. The ratio for a 44 KHz file will usually be twice the value for a 22 KHz one. The typical gain for a 44 KHz turbo tape is about 93%, which means a 12:1 compression factor! Normal speed tapes should compress even better. 
Finally, CSW files are highly compressable with the standard PC archivers such as RAR and ZIP. The packed CSW files are usually smaller than the zipped original VOCs. You will be able to RAR a 40 MB sample file down to a few hundreds KB. 
</td></tr></table></p>




<a name="CSWUTIL"></a>
<p><table bbgcolor="#ffff90" width="100%" cellspacing="12" cellpadding="0" border="0"><tr>
<td align="center" bgcolor="#ff7848" width="10%"><font size="+2" color="white"><b>
2.
</b></font></td><td><font size="+2">
The CSW utility
</font></td></tr></table>
<br>
<table width="100%" border="0"><tr><td width="10%"> </td></td><td>
This small program is intended to provide a basic support for CSW files. It can compress VOC, WAV, IFF and OUT files to CSW and decompress CSW files back to VOC format (switch -d). Enter CSW -? or simply CSW for help. At the moment, CSW.EXE accepts only uncompressed mono 8-bit sample files. Extensions in filenames can be omitted; in this case, the default extensions will be appended in turn to match an existing file. The search order is VOC, WAV, IFF and OUT for last. If the output filename is left out, the input file name with extension .CSW (or .VOC if decompressing) will be used. If the input filename ends with the extension .CSW, then the switch -d (decompression) is implicitly assumed. 
<br><br>
CSW can also work in <strong>DirectMode</strong> (switch -r), in which case the input is taken from your soundcard and conversion is performed on-the-fly in true realtime. You can stop the conversion by pressing any key at any time. To pause the recording press 'P', followed by any key to resume. During the pause, the vu-meter is shown again.
Note that, due to MakeTZX's engine requirements, the samples are written to disk anyway, so the maximum recording time is limited by the available disk space. If you want, you can keep this samples at the end of conversion and save them in a WAV file (switch -k), just in case something goes wrong and you don't want to repeat the sample. In this way, CSW may also act like a sampler!
You can set the sampling frequency with switch -s (e.g. -s44100). You can also do programmed recordings using switch -t and specifying the recording time (in seconds, e.g. -t60.0 for one minute); in this case, CSW will automatically stop when the time has elapsed (or when the disk is full), so you can start it and go away to do better things :)
<br><br>
The DirectMode SoundBlaster driver has been written for 100% compatible soundcards. If you are experiencing problems, try option "-c" which will attempt to access the hardware in a different way. The driver also performs a preliminary stability check; if this fails, CSW exits after two seconds with an error message. All this stuff is extensively covered in MakeTZX's manual, DirectMode section; please read it carefully. 
Note: In order to run the CSW utility under plain MS-DOS you need a DPMI host (such as CWSDPMI.EXE) 
Note: DirectMode, OUT files, digital filter and the other features are extensively described into MakeTZX's manual. Please read it. 
Note: Although it is possible to specify fractions of seconds, the effective recording time is subject to DMA buffer size quantums (a few 1/10ths of sec). 
Note: Like MakeTZX, CSW supports long filenames under Windows 9x 

</td></tr></table></p>



<a name="CSW2FORMAT"></a>
<p><table bbgcolor="#ffff90" width="100%" cellspacing="12" cellpadding="0" border="0"><tr>
<td align="center" bgcolor="#ff7848" width="10%"><font size="+2" color="white"><b>
3.
</b></font></td><td><font size="+2">
CSW-2 file format
</font></td></tr></table>
<br>
<table width="100%" border="0"><tr><td width="10%"> </td></td><td>

Here is the CSW implementation chart for anyone who wants to use it in some utility or emulator (if so, please let us know). The file format is very simple and the compression scheme used is somewhat based on the RLE algorithm.
<br><br>

<div align="center">

<table border=1 bgcolor="#8080D0" cellspacing="2" cellpadding="4" width="50%">
<tr bgcolor="#8080D0"><td colspan=2 align="center"><font color="#FFFFFF" size="+1"><b>Legenda</b></font></td></tr>
<tr bgcolor="#f7f7ff"><td align="center" width="30%">WORD</td><td>2 bytes</td></tr>
<tr bgcolor="#f7f7ff"><td align="center">DWORD</td><td>4 bytes</td></tr>
<tr bgcolor="#f7f7ff"><td align="center">BYTE[N]</td><td>N bytes</td></tr>
<tr bgcolor="#f7f7ff"><td align="center">ASCII[N]</td><td>N ASCII characters</td></tr>
<tr bgcolor="#f7f7ff"><td align="center">ASCIIZ[N]</td><td>ASCII string with zero-padding to N bytes total</td></tr>
<tr bgcolor="#8080D0"><td colspan=2><font color="#FFFFFF">All multi-byte values are stored in Intel byte order (little-endian).<br>
All <em>reserved</em> or undefined bits must be set to zero.
<br>
All the headers fields must be filled in; blank values are not allowed.</font></td></tr>
</table>

<br><br>


<table width="70%" border=0 cellspacing=1 cellpadding=2 bgcolor="#000000">
<tr bgcolor="#80a0ff">
<td colspan=4 align="center"><strong><font size="+2" color="#ffffff">CSW-2 Header</font></strong></td>
</tr>
<tr bgcolor="#fff000">
<td colspan=4 align="center"><font size="-2" color="#606060">CSW global file header - <strong> status: <font color="#ff6060">required</font></font></strong></td>
</tr>
<tr bgcolor="#ffdf90">
<td align="center"><strong>Offset</strong></td>
<td align="center"><strong>Value</strong></td>
<td align="center"><strong>Type</strong></td>
<td align="center"><strong>Description</strong></td>
</tr>
<tr bgcolor="#c0f0ff">
<td align="center">0x00</td>
<td align="center">(note)</td>
<td align="center">ASCII[22]</td>
<td>"Compressed Square Wave" signature</td>
</tr>
<tr bgcolor="#c0f0ff">
<td align="center">0x16</td>
<td align="center">0x1A</td>
<td align="center">BYTE</td>
<td>Terminator code</td>
</tr>
<tr bgcolor="#c0f0ff">
<td align="center">0x17</td>
<td align="center">0x02</td>
<td align="center">BYTE</td>
<td>CSW major revision number</td>
</tr>
<tr bgcolor="#c0f0ff">
<td align="center">0x18</td>
<td align="center">0x00</td>
<td align="center">BYTE</td>
<td>CSW minor revision number</td>
</tr>
<tr bgcolor="#c0f0ff">
<td align="center">0x19</td>
<td align="center">-</td>
<td align="center">DWORD</td>
<td>Sample rate</td>
</tr>
<tr bgcolor="#c0f0ff">
<td align="center">0x1D</td>
<td align="center">-</td>
<td align="center">DWORD</td>
<td>Total number of pulses (after decompression)</td>
</tr>
<tr bgcolor="#c0f0ff">
<td align="center">0x21</td>
<td align="center">-</td>
<td align="center">BYTE</td>
<td>Compression type (see notes below)<br>
<font size="1">0x01: RLE<br>
0x02: Z-RLE</font>
</td>
</tr>
<tr bgcolor="#c0f0ff">
<td align="center">0x22</td>
<td align="center">-</td>
<td align="center">BYTE</td>
<td>Flags<br>
<font size="1">b0: initial polarity; if set, the signal starts at logical high</font></td>
</tr>
<tr bgcolor="#c0f0ff">
<td align="center">0x23</td>
<td align="center">HDR</td>
<td align="center">BYTE</td>
<td>Header extension length in bytes (0x00)<br>
<font size="1">For future expansions only, see note below.</font></td>
</tr>
<tr bgcolor="#c0f0ff">
<td align="center">0x24</td>
<td align="center">-</td>
<td align="center">ASCIIZ[16]</td>
<td>Encoding application description<br>
<font size="1">Information about the tool which created the file (e.g. name and version)</font></td>
<tr bgcolor="#c0f0ff">
<td align="center">0x34</td>
<td align="center">-</td>
<td align="center">BYTE[HDR]</td>
<td>Header extension data (if present)</td>
</tr>
</tr>
<tr bgcolor="#c0f0ff">
<td align="center">0x34+HDR</td>
<td align="center">-</td>
<td align="center">-</td>
<td>CSW data.</td>
</tr>
</table>


</div>

<br><br>
<strong>Note about Header Extensions:</strong>
<br><br>
CSW-2 allows to extend the header size by a certain amount of bytes (the current default value is 0). However, this is designed for future revisions of this format and it is not meant to store application-specific data.

<br><br>
<strong>Compression types:</strong>
<br><br>
<ul>
<li><strong>0x01: RLE (Run Length Encoding)</strong><br>
The data is stored as a sequence of pulse lengths (1 byte per pulse). Consider the following scenario (each dot is a sample):
<br><br>
<img src="wave.gif" border=0>
<br><br>
The 5 pulses shown will be represented with the following bytes:<br>
03 05 01 04 07<br>
Pulse lengths greater than 0xFF (255) are represented as byte 0x00 followed by the duration represented on 4 bytes, e.g. 0xCDE9 is stored as 00 E9 CD 00 00.
</li>
<br><br>
<li><strong>0x02: Z-RLE (CSW v2.xx only)</strong><br>
Pulses are encoded exactly as in method 1, but the generated byte-stream is further compressed with the standard deflate() algorithm as defined by the <a href="http://www.gzip.org/zlib/">ZLIB</a> library (RFC 1151 and 1152). In fact the compression is equivalent to "gzip -9" (without the magic signature); the source code of the compression routines we used is the same as in our RZX SDK. [more tech details here]
</li>
</ul>

<br>
In format revision 1.01 we have introduced a bit to represent the initial signal polarity, which is not important in the Spectrum world but it is for other platforms such as C64. All the Spectrum TZX converters can safely ignore this bit (like MakeTZX does), so any tool supporting CSW 1.00 will also work fine with CSW 1.01 without modifications.
<br><br>
Note that no info about the pulse amplitude is represented because it is not necessary, since we are dealing with discrete 2-values amplitude scales.
</td></tr></table></p>





<a name="CSW1FORMAT"></a>
<p><table bbgcolor="#ffff90" width="100%" cellspacing="12" cellpadding="0" border="0"><tr>
<td align="center" bgcolor="#ff7848" width="10%"><font size="+2" color="white"><b>
4.
</b></font></td><td><font size="+2">
Old CSW v1.01 file format
</font></td></tr></table>
<br>
<table width="100%" border="0"><tr><td width="10%"> </td></td><td>
This is the format specification for the old CSW v1.01. It is reported here because a lot of existing tools support the original version of the file format.
<br><br>

<div align="center">

<table width="70%" border=0 cellspacing=1 cellpadding=2 bgcolor="#000000">
<tr bgcolor="#80a0ff">
<td colspan=4 align="center"><strong><font size="+2" color="#ffffff">CSW-1 Header</font></strong></td>
</tr>
<tr bgcolor="#fff000">
<td colspan=4 align="center"><font size="-2" color="#606060">CSW global file header - <strong> status: <font color="#ff6060">required</font></font></strong></td>
</tr>
<tr bgcolor="#ffdf90">
<td align="center"><strong>Offset</strong></td>
<td align="center"><strong>Value</strong></td>
<td align="center"><strong>Type</strong></td>
<td align="center"><strong>Description</strong></td>
</tr>
<tr bgcolor="#c0f0ff">
<td align="center">0x00</td>
<td align="center">(note)</td>
<td align="center">ASCII[22]</td>
<td>"Compressed Square Wave" signature</td>
</tr>
<tr bgcolor="#c0f0ff">
<td align="center">0x16</td>
<td align="center">0x1A</td>
<td align="center">BYTE</td>
<td>Terminator code</td>
</tr>
<tr bgcolor="#c0f0ff">
<td align="center">0x17</td>
<td align="center">0x01</td>
<td align="center">BYTE</td>
<td>CSW major revision number</td>
</tr>
<tr bgcolor="#c0f0ff">
<td align="center">0x18</td>
<td align="center">0x01</td>
<td align="center">BYTE</td>
<td>CSW minor revision number</td>
</tr>
<tr bgcolor="#c0f0ff">
<td align="center">0x19</td>
<td align="center">-</td>
<td align="center">WORD</td>
<td>Sample rate</td>
</tr>
<tr bgcolor="#c0f0ff">
<td align="center">0x1B</td>
<td align="center">0x01</td>
<td align="center">BYTE</td>
<td>Compression type<br>
<font size="1">0x01: RLE</font>
</td>
</tr>
<tr bgcolor="#c0f0ff">
<td align="center">0x1C</td>
<td align="center">-</td>
<td align="center">BYTE</td>
<td>Flags<br>
<font size="1">b0: initial polarity; if set, the signal starts at logical high</font></td>
</tr>
<tr bgcolor="#c0f0ff">
<td align="center">0x1D</td>
<td align="center">0x00</td>
<td align="center">BYTE[3]</td>
<td>Reserved.</td>
</tr>
<tr bgcolor="#c0f0ff">
<td align="center">0x20</td>
<td align="center">-</td>
<td align="center">-</td>
<td>CSW data.</td>
</tr>
</table>


</div>

<br><br>
For information about the RLE compression method (0x01) and the meaning of the polarity flag, please refer to the notes for version 2.xx.
</td></tr></table></p>





<a name="CONTACT"></a>
<p><table bbgcolor="#ffff90" width="100%" cellspacing="12" cellpadding="0" border="0"><tr>
<td align="center" bgcolor="#ff7848" width="10%"><font size="+2" color="white"><b>
5.
</b></font></td><td><font size="+2">
Contact information
</font></td></tr></table>
<br>
<table width="100%" border="0"><tr><td width="10%"> </td></td><td>
The latest version of this document can be found at:
<ul><li><a href="http://www.ramsoft.bbk.org/csw.html">http://www.ramsoft.bbk.org/csw.html</a></li></ul>
E-mails concerning the CSW specifications should be directed to:
<ul><li><a href="mailto:ramsoft@bbk.org?subject=CSW">ramsoft@bbk.org</a></li></ul>
</td></tr></table></p>




<a name="HISTORY"></a>
<p><table bbgcolor="#ffff90" width="100%" cellspacing="12" cellpadding="0" border="0"><tr>
<td align="center" bgcolor="#ff7848" width="10%"><font size="+2" color="white"><b>
6.
</b></font></td><td><font size="+2">
Revision history
</font></td></tr></table>
<br>
<table width="100%" border="0"><tr><td width="10%"> </td></td><td>
<b>Revision 2.00 (August 1st 2003)</b>
<ul>
<li>Introduced CSW revision 2.00.</li>
<li>Cleared up the document a bit.</li>
</ul>
<b>Revision 1.01 (July 13th 1999)</b>
<ul>
<li>Introduced the polarity bit (b0 in Flags)</li>
</ul>
</td></tr></table></p>


</body>
</html>
